<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Security Class - Fuel Documentation</title>
	<link href="../assets/css/main.css" media="screen" rel="stylesheet" />
	<script type="text/javascript" src="../assets/js/jquery-1.4.4.min.js"></script>
	<script type="text/javascript" src="../assets/js/nav.js"></script>
	<script type="text/javascript" src="../assets/js/highlight.pack.js"></script>
	<script type="text/javascript">
		$(function() {
			show_nav('classes', '../');
		});
		hljs.tabReplace = '    ';
		hljs.initHighlightingOnLoad();
	</script>
</head>
<body>

	<header>
		<h1>Fuel Documentation</h1>
	</header>

	<div id="main-nav"></div>

	<section id="content">
		<h2>Security Class</h2>

		<p>The security class allows you to have CSRF protection in your application.</p>

		<section>
			<h2>Configuration</h2>

			<p>
				The security class is configured through the security section of the <kbd>app/config/config.php</kbd> configuration file.
			</p>
			<p>The following security configuration settings can be defined:</p>
			<table class="config">
				<tbody>
					<tr class="header">
						<th>Param</th>
						<th>Type</th>
						<th>Default</th>
						<th>Description</th>
					</tr>
					<tr>
						<th>csrf_autoload</th>
						<td>boolean</td>
						<td><pre class="php"><code>true</code></pre></td>
						<td>
							When true, load and check the CSRF token using check_token() automatically.
						</td>
					</tr>
					<tr>
						<th>csrf_token_key</th>
						<td>string</td>
						<td><pre class="php"><code>'fuel_csrf_token'</code></pre></td>
						<td>
							Name used for the CSRF token cookie, and the name of the form field containing the token.
						</td>
					</tr>
					<tr>
						<th>csrf_expiration</th>
						<td>integer</td>
						<td><pre class="php"><code>0</code></pre></td>
						<td>
							Expiration time for the CRSF token cookie. Default, the cookie expires at end of browser session.
						</td>
					</tr>
					<tr>
						<th>uri_filter</th>
						<td>array</td>
						<td><pre class="php"><code>array('htmlentities')</code></pre></td>
						<td>
							Array of callable items (PHP functions, object methods, static class methods) used to filter the URI. By default, it uses PHP's htmlentities internal function.
						</td>
					</tr>
					<tr>
						<th>input_filter</th>
						<td>array</td>
						<td><pre class="php"><code>array()</code></pre></td>
						<td>
							Array of callable items (PHP functions, object methods, static class methods) used to filter $_GET, $_POST and $_COOKIE. By default, no input filters are defined.
						</td>
					</tr>
					<tr>
						<th>auto_encode_view_data</th>
						<td>boolean</td>
						<td><pre class="php"><code>true</code></pre></td>
						<td>
							When true, all variables passed on to view objects are automatically encoded.
						</td>
					</tr>
					<tr>
						<th>whitelisted_classes</th>
						<td>array</td>
						<td><pre class="php"><code>array('stdClass', 'Fuel\\Core\\View',<br /> 'Fuel\\Core\\ViewModel', 'Closure')</code></pre></td>
						<td>
							When auto encoding of view variables is enabled, you can run into issues when passing objects to the view. Classes defined in this
							array will be exempt from auto encoding.
						</td>
					</tr>
				</tbody>
			</table>
		</section>

		<article>
			<h4 id="method_check_token">check_token($value = null)</h4>
			<p>The <strong>check_token</strong> method allows you to check the CSRF token.<br />
			Check token also ensures a token is present and will reset the token for the next session when it receives
			a value to check (no matter the result of the check).</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$value</kbd></th>
								<td><pre class="php"><code>null</code></pre></td>
								<td>CSRF token to be checked, checks value from POST when empty.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>boolean</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>Security::check_token();</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_fetch_token">fetch_token()</h4>
			<p>The <strong>fetch_token</strong> method allows you to fetch the CSRF token from the cookie.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>None</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>string</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>$csrf_token = Security::fetch_token();</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_js_fetch_token">js_fetch_token()</h4>
			<p>The <strong>js_fetch_token</strong> method allows you to produce JavaScript fuel_csrf_token() function that will return the current CSRF token when called. Use to fill right field on form submit for AJAX operations.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>None</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>string</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>// output the javascript function
echo Security::js_fetch_token();

// you can now use the generated function in the javascript code on your page
&lt;script type="text/javascript"&gt;
	var current_token = fuel_csrf_token();
&lt;/script&gt;
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_js_set_token">js_set_token()</h4>
			<p>The <strong>js_set_token</strong> method allows you to produce JavaScript fuel_set_csrf_token() function that will set the current CSRF token field in the form when called. Use this on an onsubmit of a form, to update the hidden token field in the form with the current value of the csrf cookie.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>None</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>string</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>// output the javascript function
echo Security::js_set_token();

// you use the function generated as an onsubmit function, like so.
// do NOT forget the 'this' parameter, so the function knows which form to update!
&lt;form onsubmit="fuel_set_csrf_token(this);"&gt;
	&lt;!-- do your stuff here --&gt;
&lt;/form&gt;
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_clean">clean($value, $filters = null)</h4>
			<p>The <strong>clean</strong> method allows you clean data using the filters provided.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$value</kbd></th>
								<td><i>Required</i></td>
								<td>The value to be cleaned. This can be a string value, or an array of string values.</td>
							</tr>
							<tr>
								<th><kbd>$filters</kbd></th>
								<td><i>Required</i></td>
								<td>
									The filters to be used to clean the string(s). A filter can be a single value, or an array of values. Each value must be a valid PHP callback.
									You may specify functions ('htmlentities'), objects ($this), or static methods ('Classname::method').
								</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>string</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>// first strip tags, convert html entities in the remaining data, and finish it off using our special cleaning solution
$filters = array('strip_tags', 'htmlentities', '\\cleaners\\soap::clean');
$text = Security::clean($text, $filters);</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_strip_tags">strip_tags($value)</h4>
			<p>The <strong>strip_tags</strong> method allows you to strip HTML and PHP tags from a string.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$value</kbd></th>
								<td><i>Required</i></td>
								<td>The input string.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>string</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>$text = '&lt;p&gt;Test paragraph.&lt;/p&gt;';
$text = Security::strip_tags($text);</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_xss_clean">xss_clean($value)</h4>
			<p>The <strong>xss_clean</strong> method allows you to strip dangerous HTML tags from a string, using the HTMLawed library.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$value</kbd></th>
								<td><i>Required</i></td>
								<td>The input string.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>string</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>$text = '&lt;SCRIPT&gt;alert("XSS attack!")&lt;/SCRIPT&gt;';
$text = Security::xss_clean($text);</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_htmlentities">htmlentities($value)</h4>
			<p>
				The <strong>htmlentities</strong> method allows you to turn HTML characters into their entity equivalent. This method operates identical to PHP's htmlentities() function
				but supports arrays and objects as well.
			</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$value</kbd></th>
								<td><i>Required</i></td>
								<td>The input value.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>mixed</td>
				</tr>
				<tr>
					<th>Throws</th>
					<td><strong>RuntimeException</strong>, in case an object has been passed that can't be cast as string.</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>$text = '&lt;p&gt;Test paragraph.&lt;/p&gt;';
$text = Security::htmlentities($text);</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<h3 id="procedural_helpers">Procedural helpers</h3>

		<article>
			<h4 id="function_e">e($string)</h4>
			<p>The <strong>e</strong> function is an alias for <a href="#method_htmlentities">Security::htmlentities</a>.</p>
			<table class="method">
				<tbody>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$string</kbd></th>
								<td><em>required</em></td>
								<td>The input value.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>string, result from <a href="#method_htmlentities">Security::htmlentities</a></td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>$text = '&lt;p&gt;Test paragraph.&lt;/p&gt;';
$text = e($text);</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

	</section>

	<section id="footer">
		<p>
			<a href="http://fuelphp.com">Fuel</a> is released under the MIT license.<br />
			&copy; 2010 - 2011 Fuel Development Team
		</p>
	</section>

</body>
</html>
